feat: add OpenAI Agents SDK support to OpenInference mapper - #366

T1 — GenAI conventions ✅. Fixture chat spans carry gen_ai.operation.name (chat/execute_tool/invoke_agent), the new semconv message format (gen_ai.input.messages/gen_ai.output.messages as role/parts JSON), gen_ai.usage.*, gen_ai.agent.name/id/description. Deviations to plan for: per-turn wrapper spans with gen_ai.operation.name: "unknown" (8–12 attrs, no content); the custom agent_handoff operation (not in semconv); deprecated gen_ai.system alongside gen_ai.provider.name.

T2 — ⚠️ version-dependent, and the backfill has a semantic trap.

• In both feat(mappers): add OpenAI Agents support to GenAI session mapper #365 fixtures the claim is exactly right: the only tool-ish attributes anywhere are gen_ai.tool.call.{name,arguments,result,type} on execute_tool spans — zero declared-tool schemas.
• But the current release emits the real declared list: v0.62.3's _end_generation_span sets gen_ai.tool.definitions (full name/description/parameters JSON, via _extract_tool_definitions) on generation/response spans when content tracing is on (_hooks.py:1021-1028; runs for GenerationSpanData/ResponseSpanData, :800-803). The feat(mappers): add OpenAI Agents support to GenAI session mapper #365 fixtures simply predate it.
• So the remedy should be: prefer gen_ai.tool.definitions when present, fall back to backfill. Two reasons the backfill alone is worth improving: (i) descendant ToolExecutionSpans are tools used, not tools available — a tool-selection judge sees a shrunken candidate set with the un-chosen options missing, which is the mirror image of the false-positive bug you saw on the OpenInference side (candidate set too big there, too small here); (ii) feat(mappers): add OpenAI Agents support to GenAI session mapper #365's backfill builds ToolConfig(name=...) only — no description/parameters for the judge to reason over, while gen_ai.tool.definitions carries both.

T3 — ✅ confirmed in both fixtures. Root Agent workflow span with gen_ai.operation.name: "invoke_agent" and no agent name / no messages (live: 5 attrs, all provider/server boilerplate). Stripping is right, and #365's rule (no gen_ai.agent.name and no gen_ai.input.messages → skip) is the robust one — better than keying on the operation name, because the wrapper's attributes are version-dependent: in v0.62.3 the root gets traceloop.span.kind: workflow and no gen_ai.operation.name at all (on_trace_start, _hooks.py:676-688). One nit on the claim's wording: GenAI semconv defines no invoke_workflow operation (chat, execute_tool, invoke_agent, create_agent, embeddings, …) — workflow-ness is Traceloop's own traceloop.span.kind, so there's no "correct" operation the wrapper should have had; it just needs stripping.

T4 — ✅ confirmed. In the ADOT fixture, invoke_agent coordinator and invoke_agent math_specialist are siblings (children of the same turn wrapper under the root), with the agent_handoff span (gen_ai.handoff.from_agent: coordinator, gen_ai.handoff.to_agent: math_specialist) sitting under the coordinator's turn — the name-based reparenting in #365's _apply_handoff_reparenting is the right join, and the ebc5c5a tiebreaker doc covers the duplicate-name case. Two additions:

• The agents-as-tools pattern needs no correction — in the live fixture, execute_tool ask_math_specialist → nested invoke_agent math_specialist nests properly already. Sibling-flattening is handoff-specific.
• v0.62.3 also stamps gen_ai.agent.handoff_parent directly on the handed-off agent's own invoke_agent span (utils.py:14, applied in _start_agent_span via _reverse_handoffs_dict). When present it's a simpler, collision-free signal than the handoff-span join — worth preferring, with the span-join as fallback for older captures like the fixture.

O2 — mechanism ✅, paths and indices need precision. Verified against the v2.0.0 instrumentor source and both #366 fixtures:

• Input: plain-text messages carry the scalar llm.input_messages.N.message.content — that's the only input shape in both shipped fixtures. The contents.0.message_content.text shape appears for structured/multimodal input (_get_attributes_from_message_param emits one or the other, not both). The path as written in your comment (...message.content.0.message_content.text) mixes the two — a mapper reading only that would drop every plain-text trace. Read scalar first, contents.0...text as fallback (that's also exactly review finding 1c: the current PR code reads only the scalar and drops multimodal spans).
• Output: contents.0.message_content.text on v2.0.0, scalar .message.content on v1.6.1 — both fallbacks needed (the PR does this part right).
• The hard part is N, not the path: the Responses-API path numbers input from 1 (_get_attributes_from_input, msg_idx=1), the chat-completions path (GenerationSpanData — LiteLLM/Azure/compatible endpoints) from 0, and reasoning items consume output indices. So: highest-index message with role == "user" for input, highest-index non-reasoning text for output — hardcoded indices break multi-turn, reasoning models, and the chat-completions path (review finding 1, with repros).

O3 — ✅ verified, with one important limit. _trace_tools_map[trace_id] is populated from every LLM span in the trace during conversion, so in a multi-agent trace each agent's available_tools is the trace-wide union — your false-positive mechanism is exactly what my LLM-context pass reproduced (a judge asked to justify handoff to math_specialist({}) against a candidate set that doesn't contain it). Copying llm.tools.N.tool.json_schema onto AGENT spans fixes the scoping, but as shipped it doesn't close the bug you saw, for two reasons:

• The orchestrator's AGENT span is currently dropped (its final LLM turn is tool-calls-only, so output.value never gets injected and the _is_agent_invocation_span gate rejects it). Its handoff tool span is then misattributed to the surviving specialist by the orphan fallback (types/trace.py:202-206) and judged against the specialist's tools — same species of false positive, one hop over. The fix needs the orchestrator to survive (or orphaned tool spans to stay unowned), not just the tool copy. That's review blocker 2 / Question 1 — it's the decision this hinges on.
• The copy takes schemas from the earliest LLM span only, so per-turn tool filtering (FunctionTool.is_enabled, MCP without cache) loses entries. Deriving indices from keys and merging turns is cheap.
• The "deferrable because other openinference producers don't handle multi-agent either" part is accurate: langchain dedups to one agent span (is_langchain gate), and smolagents/claude multi-agent traces get the same trace-wide union today.

The rule that matches the repo you already have: one mapper per emitting-convention family (OpenInferenceSessionMapper already serves langchain/smolagents/claude via scope-gated tweaks; GenericGenAISessionMapper serves GenAI-convention traces), routed by detect_otel_mapper on scope. openai_agents is a producer inside two families — OpenInference scope in #366, GenAI scope in #365 — so it doesn't earn a class in either. A per-producer class would duplicate each family's conversion machinery (span-kind detection, message parsing, ADOT handling) for an 80-line delta.

Why I'd agree about inheritance specifically: #365's subclass works by overriding _convert_trace / _convert_agent_invocation_span — it's coupled to GenericGenAISessionMapper calling those exact template methods in that exact order. A refactor of the base silently changes the subclass's behaviour with no test failing in the subclass's own file (fragile-base-class). Scope-gated hooks keep the coupling visible in one place. Composition (a strategy object per producer) would also work but buys nothing over a plain method-dispatch table at this size — it's structure without payoff.

The shape I'd standardize (both mappers already approximate it):

1. Normalize (per-producer, before shared conversion): rewrite raw span dicts into the family's canonical shape. _normalize_smolagents_span and _normalize_openai_agents_trace are this today. Registered in a dispatch table rather than a growing if-chain:

   # producer scope -> (granularity, hook)
   _PRODUCER_NORMALIZERS = {
       SCOPE_OPENINFERENCE_SMOLAGENTS: ("span", _normalize_smolagents_span),
       SCOPE_OPENINFERENCE_OPENAI_AGENTS: ("trace", _normalize_openai_agents_trace),
   }

2. Convert (shared, producer-blind): one code path per family. Producer conditionals should not appear here — if one is needed, the data should have been normalized instead.
3. Post-link (per-producer where needed, after conversion): structural fixes on converted spans — feat(mappers): add OpenAI Agents support to GenAI session mapper #365's handoff reparenting and tools backfill live here; bridge_parent_gaps is the family-agnostic version and stays shared in utils.

Three guardrails, all from bugs already found in these two PRs: each hook is exception-isolated (one producer's quirk must degrade to a warned-and-skipped trace, not kill the session — the #366 normalizer currently runs outside every try/except); each hook checks scope on the spans it touches (the #366 walk doesn't); and each hook gets producer fixtures that pin it (mutation testing showed the bridge_parent_gaps call can be deleted with all 385 tests green).

Applied to the two PRs:

• feat: add OpenAI Agents SDK support to OpenInference mapper #366: keep everything in OpenInferenceSessionMapper — no new class. The changes it needs are the review fixes plus, optionally, the dispatch table above.
• feat(mappers): add OpenAI Agents support to GenAI session mapper #365: the consistent no-inheritance answer is to fold OpenAIAgentsOtelSessionMapper into GenericGenAISessionMapper: wrapper-strip becomes a normalize/skip rule, handoff-reparent + tools-backfill become a post-link step, both gated on SCOPE_OPENAI_AGENTS, and detect_otel_mapper:140-141 routes to the generic mapper. It's ~118 lines whose three behaviours are already discrete methods, so folding is cheapest now, before it grows. Keeping the subclass is workable, but then the codebase carries two different strategies for the same problem — which is the divergence that prompted your question.

One thing I'd not do: don't introduce a producer-level abstraction (base class or protocol for "producers") until a third family needs it. Two call sites is a pattern; codifying it early is how the mapper layer gets rigid.

ToolConfig.name is a required str (types/trace.py:52), so a tool schema without a usable name — e.g. an OpenAI envelope whose inner function dict lacks one, or "name": 123 — makes ToolConfig(name=None, …) raise pydantic.ValidationError, which is a ValueError subclass. That's what the removed clause was catching (the TypeError scalar-schema case it once also shielded was properly fixed in the per-span normalizer two rounds ago — that half really was stale; this half wasn't).

Same input, previous head vs this head — an AGENT span carrying one nameless schema and one good one:

at 7de7eb9:  AgentInvocationSpan count = 1   tools=['good_tool']        # bad tool skipped
at 02a76ed:  AgentInvocationSpan count = 0   (WHOLE SPAN DROPPED)
             "Failed to convert span ag: 1 validation error for ToolConfig … name … input_value=None"

The exception escapes to _build_trace's broad per-span except Exception, so one malformed tool schema silently discards the entire agent invocation — including the valid tools next to it. This is byte-for-byte the round-1 finding that motivated adding ValueError (my round-1 comment noted it was not redundant for exactly this case; the round-2 probes confirmed “that's the ValueError catch working”).

Reachability is contrived-data territory (real instrumentors emit named tools), so 🟡 not 🔴 — but it's a silent regression of this PR's own earlier behaviour. Fix: restore ValueError to the tuple, or skip schemas where not isinstance(tool_info.get("name"), str) before constructing ToolConfig. A pin test is cheap: the repro above as a unit test asserting tools == ['good_tool'] and span survival.

• A smolagents-scoped AGENT span that is an ancestor of openai_agents CHAIN/LLM spans in a shared trace is no longer normalized (attrs untouched after map_to_session — previously it got openai content injected).
• A foreign-scope LLM descendant (e.g. langchain) is no longer harvested for an openai agent's prompt/response — an openai AGENT with only foreign LLM descendants is now dropped rather than borrowing foreign content.
• The new test_foreign_scope_llm_not_used_for_agent_normalization pins the second direction. Both openai fixtures: span-tuple diff vs 7de7eb9 = 0 changes.